Advanced Elements In Microsoft Word (.docx)

Introduction

We support some advanced features specifically designed for the digital version. By using them, you can present your readers with engaging, interactive elements that will enrich your work. Please be mindful however how those digital features will be rendered in the paper version of the book. Consult the book’s editors when in doubt.

Directives

Directives are multi-line containers that allow you to place a complex element that will be interpreted by the platform. Generally, each directive consists of an opening colon fence (:::), name of a directive enclosed in braces ({directive-name}), content, and closing colon fence. Directives must be continued text without blank lines. The syntax of a directive is presented below. Later in this chapter you will find examples of many different directives.

Important

Remember, directives must be a continues text undivided by blank lines. To avoid common problems with directives that span multiple lines, you might need to use the “Shift + Enter” instead of splitting lines with “Enter” to format your equation.

YouTube/Vimeo Videos

If your video is hosted on one of the supported platforms (currently on YouTube and on Vimeo) you can embed the video using the URL. Use this syntax to add an embedded video (this is a syntax of a directive, which will be explained later).

TODO 🚧

In the future embedding a YouTube/Vimeo video should be done by adding a link to a Metadata Table:::

Important

Note that the book will then be dependent on that external source - if deleted, the video will not be rendered. We recommend uploading the videos as a file in the assets folder and referencing them via a Metadata Table.

Bear in mind that just copying the URL to video might not work. You should create a special link. For example, on youtube.com you will have to click on the “Share” button, then select the “Embed” option and copy a URL from a generated block of code.

Figure 1: How to get a link to embed a video from youtube.com

Admonitions

Admonitions highlight a particular block of text that exists slightly apart from the narrative of your page, such as a note or a warning.

To achieve that, you must use the following syntax:

Tip

Block of text that is separated from the rest of the page.

You can use different admonition types, which will be rendered using a color and an icon specific to that type. An icon might change in the future, but the general principle stays the same. Currently, the supported admonition types are as follows:

Attention

…

Caution

…

Warning

…

Danger

…

Error

…

Tip

…

Hint

…

See also

…

Important

…

Note

…

Code Blocks

Currently we do not support interactive code blocks. But you can format a static code block to show a code snippet without executing it.

TODO 🚧

Feature to be added in future releases.